TypeScript 与 ECMAScript

┌─────────────────────────────────────────────────────────────────┐
│                    TC39 提案演进流程                              │
└─────────────────────────────────────────────────────────────────┘

Stage 0             Stage 1           Stage 2           Stage 3           Stage 4
Strawman            Proposal          Draft             Candidate         Finished
(草稿)              (提案)            (草案)            (候选)            (完成)

  │                   │                 │                 │                 │
  │  TC39成员         │  Champion      │  规范初稿       │  完善规范       │  测试用例
  │  提交想法         │  负责推进       │  描述语法       │  编辑审核       │  正式合并
  │                   │                 │                 │                 │
  │                   │                 │                 │                 │
  ▼                   ▼                 ▼                 ▼                 ▼
┌──────┐          ┌──────┐          ┌──────┐          ┌──────┐          ┌──────┐
│ 任意 │─ ─ ─ ─ ─▶│ 正式 │─ ─ ─ ─ ─▶│ 初稿 │─ ─ ─ ─ ─▶│ 审核 │─ ─ ─ ─ ─▶│ 标准 │
│ 提交 │          │ 提案 │          │ 完成 │          │ 通过 │          │ 发布 │
└──────┘          └──────┘          └──────┘          └──────┘          └──────┘

不可用              不可用            不推荐使用        可试用(需编译)    官方支持

TypeScript 代码
     │
     ├─── 类型标注 ──→ 编译时擦除
     │
     └─── 新语法 ──→ 根据 target 配置降级
                        │
                        ├── target: ES3 ──→ 降级为 ES3 代码
                        ├── target: ES5 ──→ 降级为 ES5 代码
                        ├── target: ES6 ──→ 降级为 ES6 代码
                        └── target: ESNext ──→ 保持原样

const inner = obj && obj.data && obj.data.innerProperty;

const inner = obj?.data?.innerProperty;

传统方式：obj && obj.data && obj.data.innerProperty
                    ↓
可选链方式：obj?.data?.innerProperty
                    ↓
         ┌──────────┴──────────┐
         │                     │
    obj 存在？              obj 不存在
         │                     │
    访问 data              返回 undefined
         │                     │
    ┌────┴────┐                │
    │         │                │
data存在  data不存在            │
    │         │                │
访问属性   返回 undefined       │
    │         │                │
    └─────────┴────────────────┘

interface User {
  profile?: {
    name: string;
    age: number;
  };
}

const user: User = {};
const name = user?.profile?.name; // 类型为 string | undefined

const key = 'name';
const value = obj?.[key]; // 动态属性访问
const element = arr?.[0]; // 数组访问

// 更复杂的示例
obj?.[expr];      // 表达式作为属性
obj?.[++a];       // 会在短路时不执行 ++a

interface Api {
  fetchData?(): Promise<Data>;
}

const api: Api = {};
const result = await api?.fetchData?.(); // 如果方法不存在，返回 undefined

// 对应到旧写法
const result = api && api.fetchData && api.fetchData();

// 回调函数可选调用
type Callback = (() => void) | null | undefined;

let callback: Callback = null;
callback?.(); // 安全调用，如果 callback 为空则不执行

// 结合事件监听
element.addEventListener('click', (event) => {
  const target = event.target as HTMLElement | null;
  target?.click(); // 如果 target 存在则点击
});

let a = 0;
const obj = null;

// ++a 不会执行
obj?.[++a]; // a 仍然是 0

// 函数不会调用
obj?.method?.(); // method 不会被调用

const foo = someValue || fallbackValue;

const foo = someValue ?? fallbackValue;

function greet(name?: string) {
  // 错误：空字符串也会使用默认值
  const displayName = name || 'Guest';
  
  // 正确：只有 null/undefined 才使用默认值
  const displayName = name ?? 'Guest';
  
  console.log(`Hello, ${displayName}!`);
}

greet(''); // 使用 ||: Hello, Guest!  / 使用 ??: Hello, !
greet(0);  // 数字 0 作为字符串

interface Config {
  timeout?: number;
  retries?: number;
  enabled?: boolean;
}

function createConfig(userConfig?: Config): Required<Config> {
  return {
    timeout: userConfig?.timeout ?? 3000,        // 允许 timeout 为 0
    retries: userConfig?.retries ?? 3,           // 允许 retries 为 0
    enabled: userConfig?.enabled ?? true,        // 允许 enabled 为 false
  };
}

createConfig({ timeout: 0, enabled: false });
// { timeout: 0, retries: 3, enabled: false } ✓ 正确保留了 0 和 false

const bar = obj?.a?.b?.c() ?? fallbackValue;

interface ApiResponse {
  data?: {
    items: string[];
    count: number;
  };
  error?: string;
}

function handleResponse(response: ApiResponse) {
  // 获取数据，如果不存在则使用空数组
  const items = response?.data?.items ?? [];
  
  // 获取计数，如果不存在则使用 0
  const count = response?.data?.count ?? 0;
  
  // 注意：如果 count 可能是 0，使用 ?? 更安全
  // 如果使用 ||，count 为 0 时会被认为是假值
  
  return { items, count };
}

a = a + b;
a += b;

a = a - b;
a -= b;

a = a * b;
a *= b;

a = a || b;
a ||= b;

a = a && b;
a &&= b;

a = a ?? b;
a ??= b;

const options = {};

// 传统方式
if (!options.timeout) {
  options.timeout = 3000;
}

// 或赋值方式
options.timeout ||= 3000;

// 实际应用：DOM 元素初始化
function initElement(id: string) {
  const element = document.getElementById(id);
  element.style.display ||= 'block'; // 如果未设置则初始化为 block
}

let config = { debug: true };

// 只有当 config.debug 为真时才更新
config.debug &&= false; // config.debug 现在为 false

// 实际应用：条件清理
function cleanup(resources: { active?: boolean }) {
  resources.active &&= false; // 如果 active 为真，则设置为 false
}

class Cache {
  private data: Map<string, any> | null = null;
  
  get(key: string) {
    // 懒初始化：只有在首次使用时才创建
    this.data ??= new Map();
    return this.data.get(key);
  }
}

// 数组懒初始化
let arr: string[];
(arr ??= []).push("linbudu");

// 等价于以下这段
arr = arr ?? []; // 假设 arr 有可能在多处被初始化
arr.push("linbudu");

class UserService {
  private cache: Map<string, User> | null = null;
  private config: Config | null = null;
  
  async getUser(id: string): Promise<User> {
    // 懒初始化缓存
    this.cache ??= new Map();
    
    // 如果缓存存在，直接返回
    if (this.cache.has(id)) {
      return this.cache.get(id)!;
    }
    
    // 获取配置（如果未初始化则使用默认值）
    this.config ??= await this.loadConfig();
    
    // 获取用户数据
    const user = await this.fetchUser(id, this.config);
    
    // 更新缓存（只有当 user 有效时才缓存）
    user &&= this.cache.set(id, user).get(id)!;
    
    return user;
  }
}

// 传统方式：每次都会计算 getDefaultValue()
if (!obj.value) {
  obj.value = getDefaultValue(); // 只有在需要时才调用
}

// 或赋值方式：同样只有在需要时才计算
obj.value ||= getDefaultValue();

// 错误示例：总是计算右侧
obj.value = obj.value || getDefaultValue(); // 总是会调用 getDefaultValue()

{
  "compilerOptions": {
    /* 目标编译版本 */
    "target": "ES2020",
    // 可选值：ES3, ES5, ES6/ES2015, ES2016-ES2023, ESNext
    // 控制编译输出的 JavaScript 版本
    
    /* 指定使用的内置 API */
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    // 根据目标环境添加需要的类型定义
    // ES2020: 包含可选链、空值合并等
    // DOM: 包含浏览器 API
    
    /* 模块系统 */
    "module": "ESNext",
    // CommonJS, AMD, ESNext 等
    
    /* 启用严格模式 */
    "strict": true,
    // 开启所有严格类型检查选项
    
    /* 允许 JS 文件 */
    "allowJs": true,
    // 允许在 TypeScript 项目中导入 JS 文件
    
    /* 输出目录 */
    "outDir": "./dist",
    
    /* 模块解析策略 */
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

{
  "compilerOptions": {
    "lib": [
      "ES2020",           // ES2020 特性：可选链、空值合并、BigInt
      "ES2020.Promise",   // Promise 相关特性
      "ES2020.String",    // String 新方法
      "DOM",              // 浏览器 DOM API
      "DOM.Iterable",     // DOM 可迭代对象
      "ScriptHost"        // Windows Script Host
    ]
  }
}

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "module": "CommonJS",
    "moduleResolution": "node",
    "types": ["node"]
  }
}

{
  "compilerOptions": {
    "target": "ES5",
    "lib": ["ES5", "DOM"],
    "module": "CommonJS",
    "downlevelIteration": true  // 支持ES5中的迭代器
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES5",  // 降级到 ES5
    "lib": ["ES2020", "DOM"]
  }
}

npm install --save-dev @babel/core @babel/preset-env
npm install core-js

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: {
        chrome: '60',
        firefox: '60',
        safari: '11',
        edge: '17'
      },
      useBuiltIns: 'usage',
      corejs: 3
    }]
  ]
};

<!-- 使用 module/nomodule 模式 -->
<script type="module" src="modern.js"></script>
<script nomodule src="legacy.js"></script>

// ✅ 推荐：多层嵌套访问
const name = user?.profile?.personalInfo?.name;

// ✅ 推荐：方法调用
const result = obj?.method?.();

// ✅ 推荐：数组访问
const first = arr?.[0];

// ❌ 避免：过度使用
const x = obj?.a; // 如果 obj 一定存在，不需要 ?.

// ❌ 避免：赋值操作
obj?.property = value; // 语法错误，可选链不能用于赋值

// ⚠️ 注意：与 delete 结合
delete obj?.property; // 可行，但如果 obj 为空，delete 不会执行

// ✅ 推荐：保留假值（0, '', false）
const timeout = config.timeout ?? 3000;
const name = user.name ?? 'Anonymous';
const enabled = config.enabled ?? true;

// ❌ 避免：与 || 混淆
const count = items.length || 10;     // 如果 length 是 0，会使用 10
const count = items.length ?? 10;     // 如果 length 是 0，保持 0

// ✅ 推荐：配合可选链
const value = obj?.property ?? defaultValue;

// ⚠️ 注意：优先级
const x = a ?? b || c;  // 语法错误
const x = (a ?? b) || c; // 正确：使用括号明确优先级

// ✅ 推荐：懒初始化
class Service {
  private cache?: Map<string, any>;
  
  getCache() {
    return this.cache ??= new Map();
  }
}

// ✅ 推荐：配置默认值
function initConfig(config: Config) {
  config.timeout ??= 3000;
  config.retries ??= 3;
  config.debug ??= false;
  return config;
}

// ✅ 推荐：DOM 操作
function ensureElement(id: string) {
  let element = document.getElementById(id);
  element ||= document.createElement('div');
  return element;
}

// ❌ 避免：混淆使用
let x = 0;
x ??= 1; // x 仍然是 0，因为 0 不是 null/undefined

let y = 0;
y ||= 1; // y 变成 1，因为 0 是假值

// API 调用示例
interface ApiResponse<T> {
  data?: T;
  error?: {
    code: number;
    message: string;
  };
}

async function fetchUser(id: string): Promise<User> {
  const response: ApiResponse<User> = await fetch(`/api/users/${id}`).then(r => r.json());
  
  // 处理错误
  if (response.error) {
    throw new Error(response.error.message);
  }
  
  // 使用空值合并提供默认值
  const user = response.data ?? {
    id,
    name: 'Unknown',
    email: ''
  };
  
  return user;
}

// 配置合并示例
interface AppConfig {
  apiUrl?: string;
  timeout?: number;
  retries?: number;
  debug?: boolean;
}

function createAppConfig(userConfig: AppConfig = {}): Required<AppConfig> {
  return {
    apiUrl: userConfig.apiUrl ?? 'https://api.example.com',
    timeout: userConfig.timeout ?? 5000,
    retries: userConfig.retries ?? 3,
    debug: userConfig.debug ?? false
  };
}

# 检查 TypeScript 版本
npx tsc --version

# Babel 插件（如果需要）
npm install --save-dev @babel/plugin-proposal-optional-chaining
npm install --save-dev @babel/plugin-proposal-nullish-coalescing-operator

// 用户输入：可能为空字符串
const searchTerm = input || undefined; // ✅ 空字符串转为 undefined

// 计数器：可能为 0
const count = counter ?? 0; // ✅ 保留 0

// 布尔配置：可能为 false
const enabled = config.enabled ?? true; // ✅ 保留 false

// ❌ 错误：语法错误
obj?.property = value;

// ✅ 正确：先检查再赋值
if (obj) {
  obj.property = value;
}

// ✅ 正确：使用可选链读取
const value = obj?.property;

// 总是计算右侧
obj.value = obj.value || expensiveFunction();

// 只有在需要时才计算
obj.value ||= expensiveFunction();

// 第一步：替换简单的可选链
// 旧代码
if (obj && obj.data) {
  const value = obj.data.value;
}

// 新代码
const value = obj?.data?.value;

// 第二步：替换默认值逻辑
// 旧代码
const timeout = config.timeout !== undefined ? config.timeout : 3000;

// 新代码
const timeout = config.timeout ?? 3000;

// 旧的 Date API
const date = new Date('2024-01-01T00:00:00Z');
console.log(date.getMonth()); // 时区问题！

// 新的 Temporal API
const instant = Temporal.Instant.from('2024-01-01T00:00:00Z');
const zonedDateTime = instant.toZonedDateTimeISO('Asia/Shanghai');
console.log(zonedDateTime.month); // 1，更直观

const inventory = [
  { name: 'asparagus', type: 'vegetables', quantity: 5 },
  { name: 'bananas', type: 'fruit', quantity: 0 },
  { name: 'goat', type: 'meat', quantity: 23 },
];

const result = Object.groupBy(inventory, ({ type }) => type);
/*
{
  vegetables: [{ name: 'asparagus', type: 'vegetables', quantity: 5 }],
  fruit: [{ name: 'bananas', type: 'fruit', quantity: 0 }],
  meat: [{ name: 'goat', type: 'meat', quantity: 23 }]
}
*/

// 类装饰器
@logged
class Example {
  @field
  x = 0;
  
  @method
  greet() {
    return 'hello';
  }
}

import data from './data.json' with { type: 'json' };

// 动态导入
const module = await import('./module.wasm', { type: 'wasm' });

// Record
const proposal = #{
  id: 1234,
  title: "Record & Tuple proposal",
  contents: `...`,
  keywords: #["ecma", "tc39", "proposal", "record", "tuple"],
};

// Tuple
const measures = #[42, 12, 67, "measure error: foo happened"];

const a = new Set([1, 2, 3]);
const b = new Set([2, 3, 4]);

a.union(b);        // Set {1, 2, 3, 4}
a.intersection(b); // Set {2, 3}
a.difference(b);   // Set {1}
a.symmetricDifference(b); // Set {1, 4}
a.isSubsetOf(b);   // false
a.isSupersetOf(b); // false

// do expression
let x = do {
  let tmp = f();
  tmp * tmp + 1
};

let y = do {
  if (foo()) { f() }
  else if (bar()) { g() }
  else { h() }
};

// throw expression
function getEncoder(encoding) {
  const encoder = encoding === "utf8" ? new UTF8Encoder() 
                : encoding === "utf16le" ? new UTF16Encoder(false) 
                : encoding === "utf16be" ? new UTF16Encoder(true) 
                : throw new Error("Unsupported encoding");
}

// 传统写法
const result = capitalize(
  trim(
    String(user?.name ?? 'Anonymous')
  )
);

// 管道操作符
const result = user?.name ?? 'Anonymous'
  |> String(%)
  |> trim(%)
  |> capitalize(%);

function listen(element, eventName) {
    return new Observable(observer => {
        let handler = event => observer.next(event);
        element.addEventListener(eventName, handler, true);
        return () => {
            element.removeEventListener(eventName, handler, true);
        };
    });
}

const { pipe } = Function;

pipe(5, f0, f1, f2); // 等同于 f2(f1(f0(5)))

const { flow } = Function;
const f = flow(f0, f1, f2);
// 等同于 f = (...args) => f2(f1(f0(...args)))
f(5, 7); 

import type { Foo } from "foo";
import type * as Bar from "bar";

let x: string;
x = "hello";
x = 100; // 类型错误

function equals(x: number, y?: number): boolean {
    return x === y;
}

interface Person {
    name: string;
    age: number;
}

export type CoolBool = boolean;

{
  "compilerOptions": {
    "target": "ES2020"
  }
}

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

// 推荐使用 core-js 按需引入
import 'core-js/stable/Array/includes';
import 'core-js/stable/Promise';

// 或使用 @babel/preset-env 自动注入
// .babelrc
{
  "presets": [
    ["@babel/preset-env", {
      "useBuiltIns": "usage",
      "corejs": 3
    }]
  ]
}

{
  "compilerOptions": {
    "target": "ES5",           // 编译为 ES5 语法
    "lib": ["ES2020", "DOM"]   // 但可以使用 ES2020 的 API（需要 polyfill）
  }
}

interface Config {
  server?: {
    port?: number;
    host?: string;
  };
}

const config: Config = {};

// 链式使用
const port = config?.server?.port ?? 3000;
const host = config?.server?.host ?? 'localhost';

// 更复杂的链式调用
interface ApiResponse {
  data?: {
    items?: Array<{ id: number; name: string }>;
  };
}

const response: ApiResponse = {};

const firstItemName = response?.data?.items?.[0]?.name ?? 'Unknown';

// ❌ 语法错误
const result = a || b ?? c;  // SyntaxError

// ✅ 正确写法：使用括号明确优先级
const result = (a || b) ?? c;
const result = a || (b ?? c);

// 推荐做法：统一使用 ??
const result = a ?? b ?? c;

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: {
        chrome: '60',
        firefox: '60',
        safari: '11',
        edge: '17'
      },
      useBuiltIns: 'usage',
      corejs: 3
    }],
    '@babel/preset-typescript'
  ]
};

{
  "compilerOptions": {
    "lib": ["ESNext"]  // 启用最新特性支持
  }
}

// ||= - 或赋值：如果左侧为假值则赋值
let options = {};
options.debug ||= false;  // 如果 debug 不存在或为假值，设为 false
options.name ||= 'default';

// &&= - 与赋值：如果左侧为真值则赋值
let user = { name: 'John', admin: true };
user.admin &&= false;  // 如果 admin 为真，设为 false

// ??= - 空值合并赋值：如果左侧为 null/undefined 则赋值
let config = { timeout: 0 };
config.timeout ??= 3000;  // 0 不会被覆盖
config.retries ??= 3;     // undefined 会被设为 3

// 实际应用：配置合并
function initConfig(userConfig?: Partial<Config>): Config {
  const config = { ...userConfig };
  config.host ??= 'localhost';
  config.port ??= 3000;
  config.timeout ??= 5000;
  config.retries ??= 3;
  return config as Config;
}

// 提案中的语法（目前不可用）
const record = #{ x: 1, y: 2 };
const tuple = #[1, 2, 3];

// 不可变性
record.x = 3;  // TypeError

// 提案中的语法（目前不可用）
const result = match (value) {
  when { type: 'success', data }: return data;
  when { type: 'error', code }: throw new Error(code);
  default: return null;
}

// 新版装饰器语法（TypeScript 5.0+ 支持）
class Example {
  @logged
  method() {}
}

function logged(value, { kind, name }) {
  if (kind === 'method') {
    return function (...args) {
      console.log(`Calling ${name}`);
      return value.apply(this, args);
    };
  }
}

// 提案中的语法（未来可能支持）
function greet(name: string): string {
  return `Hello, ${name}!`;
}